Review — ARD ai-catalog.json publication

Tracking: #223 · Milestone: v0.4.0

Thanks for this — the concept is solid and the JSON is valid + ARD-spec-conformant. CI is green (Markdown Lint, Structural Validation, Analyze), but none of those checks verify the catalog is actually served, and as placed it won't be. One blocking issue plus some doc/catalog drift.

🔴 Blocking — catalog won't be served at the advertised URL

The file is committed to repo-root docs/.well-known/ai-catalog.json, but nothing publishes that path:

• git-ape-docs.yml builds only website/ and uploads website/build.
• Docusaurus serves static assets from website/static/ — there's no staticDirs override in docusaurus.config.ts, and scripts/generate-docs.js only writes into website/docs/; it never touches docs/.well-known/.
• So repo-root docs/** is inert and the file never lands in website/build.

Acceptance criterion #1 ("returns HTTP 200 … after merge") will fail as-is. With baseUrl: '/git-ape/', moving the file to website/static/.well-known/ai-catalog.json serves it at https://azure.github.io/git-ape/.well-known/ai-catalog.json.

🟠 Should fix — ard.md + PR description describe a catalog that no longer exists

The last commit (98c20b6, "remove ARD collections") emptied collections to [], but website/docs/reference/ard.md still:

• has the "federates two additional skill catalogs via collections" paragraph,
• shows the 2-row Collections table (SaaS / AWS),
• shows collections[] with 2 URLs in the JSON sample,
• claims agents "discover all 48 skills (15 + 12 + 21)".

All false against the shipped catalog (15 skills, no collections). The PR description carries the same stale claims. Please either re-add the collections or scrub these so the doc matches what ships.

🟡 Nits

• host.identifier: "azure.github.io" implies the ARD well-known URL https://azure.github.io/.well-known/ai-catalog.json (domain root). A GitHub Pages project site can only serve /git-ape/…, not the domain root, so the catalog is registrable manually but not auto-discoverable at the azure.github.io root. Worth a note in the doc.
• "descriptions sourced directly from SKILL.md frontmatter" isn't quite accurate — they're editorially cleaned/truncated (e.g. prereq-check is fully rewritten; azure-drift-detector / azure-cost-estimator drop trailing "Use…" sentences). The cleanup is an improvement; just the claim is misleading.
• type: "application/ai-skill" — the ARD example uses application/mcp-server+json. The spec lists "Skill" as a resource kind but doesn't pin a media type; worth confirming application/ai-skill is the token crawlers expect.
• ard.md has no trailing newline (diff shows "No newline at end of file").

✅ Good

JSON is valid, envelope conforms to ARD v1.0 (specVersion / host / entries / collections), and all 15 entries correctly match the 15 dirs in .github/skills/.

Pushed fixes (commit 317c3bb)

Addressed the review items from above directly on feat/ard-catalog:

🔴 Blocking — now resolved

• Moved the catalog from repo-root docs/.well-known/ai-catalog.json (never published by the Pages build) to website/static/.well-known/ai-catalog.json (100% pure rename, JSON unchanged), and removed the now-empty repo-root docs/.
• Verified with a real production build (npm ci → node scripts/generate-docs.js → npm run build): build/.well-known/ai-catalog.json is emitted and valid JSON, so https://azure.github.io/git-ape/.well-known/ai-catalog.json will return 200 after merge.

🟠 Doc drift — now resolved

• Reconciled website/docs/reference/ard.md with the shipped catalog (collections: []): removed the SaaS/AWS collections table, the collections[] URLs in the JSON sample, the federation prose, and the "48 skills" total (→ 15 Git-Ape skills).
• Added a note that the docs are a Pages project site (served under /git-ape/, not the azure.github.io root).
• Softened "sourced directly from SKILL.md frontmatter" → "derived … (condensed for length)".
• Added the missing trailing newline.
• build/docs/reference/ard.html renders clean — no stale 48/SaaS/AWS references.

Also updated the PR description to match (no collections, correct file path, corrected acceptance criteria).

Not changed: type: "application/ai-skill" — left as-is. The ARD spec lists "Skill" as a resource kind but doesn't pin a media type, and application/mcp-server+json (the spec's example) would be wrong for a skill. Flag if you'd prefer a different token.